Shape-Related Functions Applicable to Geometric Shapes (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 2 - Geometric Shapes / Applying Functions Described Elsewhere to Geometric Shapes

Shape-Related Functions Applicable to Geometric Shapes
You can apply all of the functions described in the chapter "Shape Objects" in Inside Macintosh: QuickDraw GX Objects to geometric shapes. These functions allow you to

manipulate the shape object that represents geometric shapes (for example, you can copy, clone, cache, compare, and dispose of a geometric shape)
set the geometry, shape type, shape fill, and shape attributes of geometric shapes
change the style, ink, and transform objects that are associated with geometric shapes
manipulate the tags and owner count of the geometric shapes

Table 2-1 gives important information about geometric shapes for a subset of the functions from the chapter "Shape Objects" in Inside Macintosh: QuickDraw GX Objects. Functions described in that chapter that do not appear in this list exhibit the same behavior when applied to geometric shapes as they do when applied to other types of shapes.
Table 2-1 Shape-related functions that exhibit special behavior with geometric shapes
Function name Action taken
GXGetDefaultShape Returns a reference to the default geometric shape of the specified type. See "The Geometric Shape Types" beginning on page 2-16 for information about the default geometric shapes.
GXGetShapeFill Returns the shape fill of the shape. See "The Geometric Shape Types" beginning on page 2-16 for a discussion of which shape fills are appropriate for which geometric shapes.
GXSetDefaultShape Allows you to specify the shape to copy when creating new geometric shapes. See "The Geometric Shape Types" beginning on page 2-16 for information about the default geometric shapes.
GXSetShapeFill Sets the shape fill of the shape. See "The Geometric Shape Types" beginning on page 2-16 for a discussion of which shape fills are appropriate for which geometric shapes.
GXSetShapeType Changes the shape type of the geometric shape and converts the shape fill and geometry as appropriate. See the rest of this section for more information about converting shape types.

When converting between geometric shape types, the behavior of the GXSetShapeType function depends on the new shape type. If the new shape type is the point, line or rectangle type, the new geometry is based on the bounding rectangle of the original geometry:
Old type New type New geometry
Any Point Upper-left corner of bounds
Any Line Line from upper-left corner to lower-left corner
Any Rectangle Bounding rectangle of original geometry

For examples, see "Converting Between Geometric Shape Types" beginning on page 2-65.
If the new shape type is the curve type, the conversion performed depends on the original shape type:
Old type New type New geometry
Point Curve New control points all set to original point
Line Curve First and last points remain the same;
off-curve control point set equal to last point
Rectangle Curve First point set to original upper-left point;
last point set to original lower-right point;
off-curve control point set equal to last point
Polygon Curve New control points set to first three original control points
Path Curve New control points set to first three original control points

For examples, see "Converting Shapes to Curve Shapes" beginning on page 2-71.
If the new shape type is the polygon type, this function retains all of the original geometric points:
Old type New type New geometry
Point, line, or rectangle Polygon
Single contour with same geometric points
Curve Polygon Single contour with same geometric points;
the off-curve point becomes on curve
Path Polygon Same geometric points; all on curve
(calculates approximation if curve error is not zero)

When converting a path shape to a polygon shape, this function examines the curve error of the style of the path shape. If the curve error is not zero, this functions creates a polygon approximation of the original path. For more information about curve error, see the next chapter, "Geometric Styles," in this book.
Finally, if the new shape type is the path type, the GXSetShapeType function retains all of the original geometry information:
Old type New type New geometry
Point, line, curve,
or rectangle Path Single contour with same geometric points
Polygon Path Same number of contours; same geometric points;
all control points remain on curve

For examples, see "Converting Shapes to Polygons and Paths" beginning on page 2-74.

**Table 2-1 Shape-related functions that exhibit special behavior with geometric shapes**
Function name	Action taken
GXGetDefaultShape	Returns a reference to the default geometric shape of the specified type. See "The Geometric Shape Types" beginning on page 2-16 for information about the default geometric shapes.
GXGetShapeFill	Returns the shape fill of the shape. See "The Geometric Shape Types" beginning on page 2-16 for a discussion of which shape fills are appropriate for which geometric shapes.
GXSetDefaultShape	Allows you to specify the shape to copy when creating new geometric shapes. See "The Geometric Shape Types" beginning on page 2-16 for information about the default geometric shapes.
GXSetShapeFill	Sets the shape fill of the shape. See "The Geometric Shape Types" beginning on page 2-16 for a discussion of which shape fills are appropriate for which geometric shapes.
GXSetShapeType	Changes the shape type of the geometric shape and converts the shape fill and geometry as appropriate. See the rest of this section for more information about converting shape types.

Old type	New type	New geometry
Any	Point	Upper-left corner of bounds
Any	Line	Line from upper-left corner to lower-left corner
Any	Rectangle	Bounding rectangle of original geometry

Old type	New type	New geometry
Point	Curve	New control points all set to original point
Line	Curve	First and last points remain the same; off-curve control point set equal to last point
Rectangle	Curve	First point set to original upper-left point; last point set to original lower-right point; off-curve control point set equal to last point
Polygon	Curve	New control points set to first three original control points
Path	Curve	New control points set to first three original control points

Old type	New type	New geometry
Point, line, or rectangle	Polygon	Single contour with same geometric points
Curve	Polygon	Single contour with same geometric points; the off-curve point becomes on curve
Path	Polygon	Same geometric points; all on curve (calculates approximation if curve error is not zero)

Old type	New type	New geometry
Point, line, curve, or rectangle	Path	Single contour with same geometric points
Polygon	Path	Same number of contours; same geometric points; all control points remain on curve